home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / dirent.lha / dirent / NOTES < prev    next >
Text File  |  1988-07-09  |  5KB  |  109 lines
  1.  
  2.  
  3. NOTES FOR NEARLY-POSIX-COMPATIBLE C LIBRARY DIRECTORY-ACCESS ROUTINES
  4.  
  5.  
  6. Older UNIX C libraries lacked support for reading directories, so historically
  7. programs had knowledge of UNIX directory structure hard-coded into them.  When
  8. Berkeley changed the format of directories for 4.2BSD, it became necessary to
  9. change programs to work with the new structure.  Fortunately, Berkeley designed
  10. a small set of directory access routines to encapsulate knowledge of the new
  11. directory format so that user programs could deal with directory entries as an
  12. abstract data type.  (Unfortunately, they didn't get it quite right.)  The
  13. interface to these routines was nearly independent of the particular
  14. implementation of directories on any given UNIX system; this has become a
  15. particularly important requirement with the advent of heterogeneous network
  16. filesystems such as NFS.
  17.  
  18. It has consequently become possible to write portable applications that search
  19. directories by restricting all directory access to use these new interface
  20. routines.  The sources supplied here are a total rewrite of Berkeley's code,
  21. incorporating ideas from a variety of sources and conforming as closely to
  22. published standards as possible, and are in the PUBLIC DOMAIN to encourage
  23. their widespread adoption.  They support four methods of access to system
  24. directories: the original UNIX filesystem via read(), the 4.2BSD filesystem via
  25. read(), NFS and native filesystems via getdirentries(), and SVR3 getdents().
  26. The other three types are accomplished by appropriate emulation of the SVR3
  27. getdents() system call, which attains portability at the cost of slightly more
  28. data movement than absolutely necessary for some systems.  These routines
  29. should be added to the standard C library on all UNIX systems, and all existing
  30. and future applications should be changed to use this interface.  Once this is
  31. done, there should be no portability problems due to differences in underlying
  32. directory structures among UNIX systems.  (When porting your applications to
  33. other UNIX systems, you can always carry this package around with you.)
  34.  
  35. An additional benefit of these routines is that they buffer directory input,
  36. which provides improved access speed over raw read()s of one entry at a time.
  37.  
  38. One annoying compatibility problem has arisen along the way, namely that the
  39. original Berkeley interface used the same name, struct direct, for the new data
  40. structure as had been used for the original UNIX filesystem directory record
  41. structure.  This name was changed by the IEEE 1003.1 (POSIX) Working Group to
  42. "struct dirent" and was picked up for SVR3 under the new name; it is also the
  43. name used in this portable package.  I believe it is necessary to bite the
  44. bullet and adopt the new non-conflicting name.  Code using a 4.2BSD-compatible
  45. package needs to be slightly revised to work with this new package, as follows:
  46.     Change
  47.         #include <ndir.h>    /* Ninth Edition UNIX */
  48.     or
  49.         #include <sys/dir.h>    /* 4.2BSD */
  50.     or
  51.         #include <dir.h>    /* BRL System V emulation */
  52.     to
  53.         #include <sys/types.h>    /* if not already #included */
  54.         #include <dirent.h>
  55.  
  56.     Change
  57.         struct direct
  58.     to
  59.         struct dirent
  60.  
  61.     Change
  62.         (anything)->d_namlen
  63.     to
  64.         strlen( (anything)->d_name )
  65.  
  66. There is a minor compatibility problem in that the closedir() function was
  67. originally defined to have type void, but IEEE 1003.1 changed this to type int,
  68. which is what this implementation supports (even though I disagree with the
  69. change).  However, the difference does not affect most applications.
  70.  
  71. Another minor problem is that IEEE 1003.1 defined the d_name member of a struct
  72. dirent to be an array of maximum length; this does not permit use of compact
  73. variable-length entries directly from a directory block buffer.  This part of
  74. the specification is incompatible with efficient use of the getdents() system
  75. call, and I have therefore chosen to follow the SVID specification instead of
  76. IEEE 1003.1 (which I hope is changed for the final-use standard).  This
  77. deviation should have little or no impact on sensibly-coded applications, since
  78. the relevant d_name length is that given by strlen(), not the declared array
  79. size.
  80.  
  81. Error handling is not completely satisfactory, due to the variety of possible
  82. failure modes in a general setting.  For example, the rewinddir() function
  83. might fail, but there is no good way to indicate this.  I have tried to
  84. follow the specifications in IEEE 1003.1 and the SVID as closely as possible,
  85. but there are minor deviations in this regard.  Applications should not rely
  86. too heavily on exact failure mode semantics.
  87.  
  88. Please do not change the new standard interface in any way, as that would
  89. defeat the major purpose of this package!  (It's okay to alter the internal
  90. implementation if you really have to, although I tried to make this unnecessary
  91. for the vast majority of UNIX variants.)
  92.  
  93. Installation instructions can be found in the file named INSTALL.
  94.  
  95. This implementation is provided by:
  96.  
  97.     Douglas A. Gwyn
  98.     U.S. Army Ballistic Research Laboratory
  99.     SLCBR-VL-V
  100.     Aberdeen Proving Ground, MD 21005-5066
  101.  
  102.     (301)278-6647
  103.  
  104.     Gwyn@BRL.MIL or seismo!brl!gwyn
  105.  
  106. This is UNSUPPORTED, use-at-your-own-risk, free software in the public domain.
  107. However, I would appreciate hearing of any actual bugs you find in this
  108. implementation and/or any improvements you come up with.
  109.